<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
  <meta name="generator" content="Context">
  <meta name="Author" content="Cearn">
  <meta name="Created" content="20070317">
  <meta name="Modified" content="20081207">

  <title>Grit: GBA Image Transmogrifier</title>
  <link rel="stylesheet" type="text/css" href="tonc.css">
  <script language="JavaScript" type="text/javascript" src="tonc.js"></script>
</head>
<body onload="main();">

<!--567890123456789012345678901234567890123456789012345678901234567-->


<!-- [[header]] -->
<table class=header>
<tr>
  <td class=hdr_l><a href="index.htm">Prev</a>
  <td class=hdr_c><a href="index.htm">Contents</a>
  <td class=hdr_r><a href="gritmake.htm">Next</a>
</table>
<!-- [[/header]] -->

<hr>

<h1 id="ch-grit">
  Grit v0.8.3</h1>

<!-- [[toc]] -->
<ul>
  <li><a href="#sec-intro">Introduction</a></li>
  <li><a href="#sec-opts">List of options</a></li>
  <li><a href="#sec-dwim">DWIM</a></li>
  <li><a href="#sec-eg">Examples</a></li>
  <li><a href="#sec-info">Additional information</a></li>
</ul>
<!-- [[/toc]] -->


<!-- ============================================================== -->

<h2 id="sec-intro">1.1.
  Introduction</h2>

<p>
The GBA Image Transmogrifier (&ldquo;grit&rdquo; for short) is a bitmap 
conversion tool for GBA/NDS development. It accepts a multitude of 
file types (bmp, pcx, png, gif, etc) at any bitdepth and can convert 
them to palette, graphics and/or map data that can be used directly 
in GBA code. The output formats are C/asm arrays, raw binary files 
GBFS files, and a RIFF-format I call GRF. The data can be compressed to 
fit the BIOS decompression routines.
</p>
<p>
Grit can do more than simply turn bitmap into arrays. It allows you to 
crop or enlarge the original work area, convert between bitdepths, 
break the images up into tiles or metatiles and supports NDS 
bitmaps with transparency. It also has a number of tile-mapping 
options: it can take the bitmap and turn it into a tilemap (and metamap) 
and a set of unique tiles. It can also merge the palettes or tilesets from 
multiple files.
</p>
<p>
If you need more, feel free to add your own code. This is an open-source 
project and the code should compile on all platforms, though you'll 
have to write your own makefiles for non-Windows environments.
</p><br>

<p class=ni>
Grit comes in two flavors: a command-line version, <tt>grit</tt>, and a 
Windows GUI, <tt>wingrit</tt>. This is the documentation for the 
command-line version.
</p>



<!-- ============================================================== -->

<h2 id="sec-opts">1.2.
  List of options</h2>


<h3 id="ssec-opts-gfx">1.2.1..
  Graphics options</h3>

<dl>

<dt>-g</dt>
<dd>
Include graphics in output.
</dd>

<dt>-g!</dt>
<dd>
Exclude graphics from output.
</dd>

<dt>-gb</dt>
<dd>
Bitmapped graphics output. NOTE: without an <tt>-gT</tt> option, this 
data will have a clear bit 15.
</dd>

<dt>-gt</dt>
<dd>
Tiled graphics output (default).
</dd>

<dt>-ga &lt;n&gt;</dt>
<dd>
Pixel offset for non-zero pixels. Useful if the associated palette is 
at an offset.
</dd>

<dt>-gB &lt;n&gt;</dt>
<dd>
Bit depth of the output. Can be 1, 2, 4, 8 or 16. 16 bpp is a 
truecolor mode, the rest are paletted. If the source image is not of 
this bitdepth yet, it will be converted.
</dd>

<dt>-gS</dt>
<dd>
Shared graphics. Build up a shared tileset for the multiple images. 
See also <tt>-fx</tt>, <tt>-S</tt> and <tt>-O</tt>. 
</dd>

<dt>-gT [ &lt;h&gt; ]</dt>
<dd>
Transparent color. The color should be a 16bit BGR color or 24bit RGB 
color in hex. For truecolor output, all pixels will have the alpha-bit 
set except this color. For paletted output, this color will be 
transferred into index 0.
</dd>

<dt>-gT!</dt>
<dd>
No transparent pixels / set the alpha-bit of the pixels. Only has effect 
for NDS bitmaps.
</dd>

<dt>-gu8</dt>
<dd>
Graphics data is in byte arrays.
</dd>

<dt>-gu16</dt>
<dd>
Graphics data is in halfword arrays.
</dd>

<dt>-gu32</dt>
<dd>
Graphics data is in word arrays (default).
</dd>

<dt>-gz!</dt>
<dd>
Graphics data is not compressed. (default)
</dd>

<dt>-gz0</dt>
<dd>
As <tt>-gz!</tt>, but with a compression header. byte 0: 0x00, 
bytes 1-3: size of data.
</dd>

<dt>-gzh</dt>
<dd>
Graphics data is 8-bit Huffman compressed.
</dd>

<dt>-gzl</dt>
<dd>
Graphics data is LZ77 compressed.
</dd>

<dt>-gzr</dt>
<dd>
Graphics data is RLE compressed.
</dd>

</dl>


<h3 id="ssec-opts-area">1.2.2.
  Area options</h3>

<dl>

<dt>-ab &lt;n&gt;</dt>
<dd>
Bottom side of the work bitmap's rectangle. If this falls outside of 
the source bitmap, the latter will be extended.
</dd>

<dt>-ah &lt;n&gt;</dt>
<dd>
Height side of the work bitmap's rectangle. If this makes the bottom 
fall outside of the source bitmap, the latter will be extended.
</dd>

<dt>-al &lt;n&gt;</dt>
<dd>
Left side of the work bitmap's rectangle. If this falls outside of 
the source bitmap, the latter will be extended.
</dd>

<dt>-ar &lt;n&gt;</dt>
<dd>
Right side of the work bitmap's rectangle. If this falls outside of 
the source bitmap, the latter will be extended.
</dd>

<dt>-at &lt;n&gt;</dt>
<dd>
Top side of the work bitmap's rectangle. If this falls outside of the 
source bitmap, the latter will be extended.
</dd>

<dt>-aw &lt;n&gt;</dt>
<dd>
Width of the work bitmap's rectangle. If this makes the right side 
fall outside of the source bitmap, the latter will be extended.
</dd>

</dl>


<h3 id="ssec-opts-map">1.2.3.
  Map options</h3>

<dl>

<dt>-m</dt>
<dd>
Include map in output. Enables tile-mapping of the image.
</dd>

<dt>-m!</dt>
<dd>
Exclude map from output (default).
</dd>

<dt>-ma &lt;n&gt;</dt>
<dd>
Tile index offset (non-zero indices only). Useful if you intend to 
load the tiles at an offset.
</dd>

<dt>-mLa</dt>
<dd>
Map layout for affine tilemaps: 8-bit screen entries and a flat map.
</dd>

<dt>-mLf</dt>
<dd>
Map layout for regular backgrounds. 16-bit entries, but a flat map 
(i.e., not broken down into screenblocks).
</dd>

<dt>-mLs</dt>
<dd>
Map layout for regular backgrounds. 16-bit entries, broken down into 
screenblocks.
</dd>

<dt>-mR!</dt>
<dd>
Disable tile reduction for tilemaps.
</dd>

<dt>-mR4</dt>
<dd>
Tile reduction combo for regular backgrounds with 4bpp tiles: tile, 
palette and flip reduction.
</dd>

<dt>-mR8</dt>
<dd>
Tile reduction combo for regular backgrounds with 8bpp tiles: tile and 
flip reduction.
</dd>

<dt>-mRa</dt>
<dd>
Tile reduction combo for affine backgrounds: tile reduction only.
</dd>

<dt>-mRf</dt>
<dd>
Tile reduction option: reduce for flipped tiles. Can be combined with 
<tt>t</tt> and <tt>p</tt> reduction options (example: <tt>-mRtpf</tt>).
</dd>

<dt>-mRp</dt>
<dd>
Tile reduction option: reduce for 16-color palette banks. Can be 
combined with <tt>t</tt> and <tt>f</tt> reduction options (example: 
<tt>-mRtpf</tt>). Do not use this for 8bpp tiles ^ndash; you'll regret it.
</dd>

<dt>-mRt</dt>
<dd>
Tile reduction option: reduce for unique tiles. Can be combined with 
<tt>p</tt> and <tt>f</tt> reduction options (example: <tt>-mRtpf</tt>).
</dd>

<dt>-mu8</dt>
<dd>
Map data is in byte arrays.
</dd>

<dt>-mu16</dt>
<dd>
Map data is in halfword arrays (deafult).
</dd>

<dt>-mu32</dt>
<dd>
Map data is in word arrays.
</dd>

<dt>-mz!</dt>
<dd>
Map data is not compressed. (default)
</dd>

<dt>-mz0</dt>
<dd>
As <tt>-mz!</tt>, but with a compression header. byte 0: 0x00, 
bytes 1-3: size of data.
</dd>

<dt>-mzh</dt>
<dd>
Map data is 8-bit Huffman compressed.
</dd>

<dt>-mzl</dt>
<dd>
Map data is LZ77 compressed.
</dd>

<dt>-mzr</dt>
<dd>
Map data is RLE compressed.
</dd>

</dl>


<h3 id="ssec-opts-meta">1.2.4.
  Metamap/object options</h3>

<dl>

<dt>-Mh</dt>
<dd>
Metatile height. Useful for keeping the tiles in a metatile/object 
together. If tile-mapping is enabled, this will enable metamapping. 
Works together with <tt>-Mw</tt>.
</dd>

<dt>-Mw</dt>
<dd>
Metatile width. Useful for keeping the tiles in a metatile/object 
together. If tile-mapping is enabled, this will enable metamapping. 
Works together with <tt>-Mh</tt>.
</dd>

<dt>-MRp</dt>
<dd>
Metatile palette reduction.
</dd>

</dl>

<h3 id="ssec-opts-pal">1.2.5.
  Palette options</h3>

<dl>

<dt>-p</dt>
<dd>
Include palette in output (default).
</dd>

<dt>-p!</dt>
<dd>
Exclude palette from output.
</dd>

<dt>-pe &lt;n&gt;</dt>
<dd>
End' palette entry. For example, <tt>-pe 32</tt> would output the 
palette up to, but not including, color 32. Works together with <tt>-ps</tt>.
</dd>

<dt>-pn &lt;n&gt;</dt>
<dd>
Number of palette entries. Works together with <tt>-ps</tt>; 
overrules <tt>-pe</tt>.
</dd>

<dt>-ps &lt;n&gt;</dt>
<dd>
Starting palette entry. <tt>-ps 16</tt> would start the export at 
color 16. Works together with <tt>-pe</tt> and <tt>-pn</tt>.
</dd>

<dt>-pS</dt>
<dd>
Shared palette data. The colors of the source bitmaps are merged into 
a single palette. See also <tt>-O</tt> and <tt>-S</tt>. 
<dfn>NOTE</dfn>: will alter the order of the original palette (unless 
the first bitmap happened to have all the colors in it (hint, hint)). 
</dd>

<dt>-pT &lt;n&gt;</dt>
<dd>
Transparent palette index. Only works if the input or output is 
paletted. For paletted output, it'll swap the transparent index with 
index 0 so that that becomes the transparent index. For paletted &rarr; 
truecolor conversion, the color of the transparent index will be used for 
transparency, working as a <tt>-gT</tt> option.
</dd>

<dt>-pu8</dt>
<dd>
Palette data is in byte arrays.
</dd>

<dt>-pu16</dt>
<dd>
Palette data is in halfword arrays (default).
</dd>

<dt>-pu32</dt>
<dd>
Palette data is in word arrays.
</dd>

<dt>-pz!</dt>
<dd>
Palette data is not compressed. (default)
</dd>

<dt>-pz0</dt>
<dd>
As <tt>-pz!</tt>, but with a compression header. byte 0: 0x00, 
bytes 1-3: size of data.
</dd>

<dt>-pzh</dt>
<dd>
Palette data is 8-bit Huffman compressed.
</dd>

<dt>-pzl</dt>
<dd>
Palette data is LZ77 compressed.
</dd>

<dt>-pzr</dt>
<dd>
Palette data is RLE compressed.
</dd>

</dl>


<h3 id="ssec-opts-io">1.2.6.
  Input/output options</h3>

<dl>

<dt>-fa</dt>
<dd>
Append to output file instead of overwriting. If data with the symbol 
name already exists in the file, it will be replaced. Has no effect 
for binary output.
</dd>

<dt>-ff &lt;path&gt;</dt>
<dd>
Flag file for additional options. Instead of adding all the options 
to the makefile, you can use an external file to store and modify them.
</dd>

<dt>-fh</dt>
<dd>
Create header file with declarations and array length definitions 
(using array-name + <tt>Len</tt>). 
</dd>

<dt>-fh!</dt>
<dd>
Do not create header file with declarations.
</dd>

<dt>-fr</dt>
<dd>
Group the separate arrays into a GRF-formatted array. See also 
<tt>-ftr</tt>.
</dd>

<dt>-ftb</dt>
<dd>
Export to binary files. Each array will have its own file: palettes 
will go into <tt>*.pal.bin</tt>; graphics data into <tt>*.img.bin</tt>; 
map data into <tt>*.map.bin</tt>; metamap data into <tt>*.meta.bin</tt>.
</dd>

<dt>-ftc</dt>
<dd>
Export to C arrays.
</dd>

<dt>-ftg</dt>
<dd>
Export to <a href="http://www.pineight.com">PinEight GBFS</a> format. 
Note that the GBFS entry names are limited to 24 characters, 6 of which 
are already used for data affixes.
</dd>

<dt>-ftr</dt>
<dd>
Export to GRF (Grit RIFF). See <a href="#ssec-info-grf">notes</a> for 
details.
</dd>


<dt>-fts</dt>
<dd>
Export to GNU assembly arrays. Default output filetype.
</dd>

<dt>-fx &lt;path&gt;</dt>
<dd>
External tileset bitmap which can then be shared between different 
tilemaps. Implies <tt>-gS</tt>. 
<b><i>NOTE</i></b>. This is still a little fickle. The file must already 
be in the correct format: a column or reduced tiles with 8bpp. If the 
file-type does not support 8bpp, a <tt>.bmp</tt> of the same name will 
be used. <tt>-fx</tt> works a little differently in v0.8 than before. 
See <a href="#ssec-info-shared">info:shared</a> for details.
</dd>

<dt>-o &lt;path&gt;</dt>
<dd>
Output file path. 
</dd>

<dt>-O &lt;path&gt;</dt>
<dd>
Output file path for shared data. 
</dd>

<dt>-s &lt;name&gt;</dt>
<dd>
Base name for array symbols. Invalid identifier characters will be 
replaced by underscores. If this option is not given, then the name 
follows from the output title, or from the input title if <tt>-fa</tt> 
is given.
</dd>

<dt>-S &lt;path&gt;</dt>
<dd>
Base name for symbols for shared data.
</dd>
</dl>


<h3 id="ssec-opts-misc">1.2.7.
  Misc options</h3>

<dl>

<dt>-tc</dt>
<dd>
Tiling is done in column-major order, instead of row-major. This 
can be useful for horizontal scrollers, or efficient tile rendering.
</dd>

<dt>-q</dt>
<dd>
Quiet mode. Don't print report at the end. May be obsolete thanks to 
the new logging functions.
</dd>

<dt>-U8</dt>
<dd>
Set all output to use byte arrays.
</dd>

<dt>-U16</dt>
<dd>
Set all output to use halfword arrays.
</dd>

<dt>-U32</dt>
<dd>
Set all output to use word arrays.
</dd>

<dt>-Z!</dt>
<dd>
Set all output to use no compression.
</dd>

<dt>-Z0</dt>
<dd>
As <tt>-Z!</tt>, but with a compression header. byte 0: 0x00, 
bytes 1-3: size of data.
</dd>

<dt>-Zh</dt>
<dd>
Set all output to use 8-bit Huffman compression.
</dd>

<dt>-Zl</dt>
<dd>
Set all output to use LZ77 compression.
</dd>

<dt>-Zr</dt>
<dd>
Set all output to use RLE compression.
</dd>

<dt>-W1</dt>
<dd>
Log error messages.
</dd>

<dt>-W2</dt>
<dd>
Log errors and warning messages.
</dd>

<dt>-W3</dt>
<dd>
Log error, warning and status messages. There are a <i>lot</i> of 
status messages, so this is mainly for debugging.
</dd>

<dt>-We</dt>
<dd>
See <tt>-W1</tt>.
</dd>

<dt>-Ws</dt>
<dd>
See <tt>-W2</tt>.
</dd>

<dt>-Ww</dt>
<dd>
See <tt>-W3</tt>.
</dd>

</dl>

<!-- ============================================================== -->

<h2 id="sec-dwim">1.3.
  DWIM</h2>
<p>
For those who don't know, &ldquo;<a>DWIM</a>&rdquo; stands for 
&ldquo;<a href="http://en.wikipedia.org/wiki/DWIM">Do What I mean</a>&rdquo;, 
in the sense that grit attempts to guess at options that aren't specified 
explicitly, or correct for options that conflict, rather than quite and 
yell at you. In principle, this can be considered a Good Thing, but it 
does make it harder to predict exactly what will happen at times. 
</p>
<p>
The list here covers the various defaults and overrides that Grit 
uses. I'll try to make it as complete and accurate as possible, but it 
sometimes gets so convoluted that even I don't know anymore 
<kbd>^_^;;</kbd>. If you find something that's wring or missing here, 
please let me know.
</p>

<h3 id="ssec-dwim-dflt">1.3.1.
  Default settings</h3>

<ul>
  <li>
    <b>Exported data</b>: palette and graphics data is exported 
    by default, tile-maps are not (<tt>-p -g -m!</tt> options). No 
	compression.
  </li>
  <li>
    <b>Palette</b>: palette data will consist of the full palette 
    of the input bitmap. What this actually means depends on the 
	bitdepth.
  </li>
  <li>
    <b>Graphics format</b>. Tiled graphics in the input bitmap's 
    bitdepth for paletted images (<tt>-gt</tt>). Or 16bpp bitmap for 
	truecolor images (<tt>gb</tt>).
  </li>
  <li>
    <b>Bitmap transparency</b>. The alpha-bit will be clear if 
    no <tt>-gT</tt> option is given. For a colorless <tt>-gT</tt>, 
	magenta will be used to indicate the transparent color.
  </li>
  <li>
    <b>Area</b>: size of the input bitmap.
  </li>
  <li>
    <b>Mapping: tile reduction</b>: reduce for unique and flipped tiles 
	(<tt>-mR8</tt>).
	<i>NOTE</i>: grit will always start a new tileset with an empty 
	 tile.
  </li>
  <li>
    <b>Mapping: layout</b>: regular screen entries, flat map 
	(<tt>-mLf</tt>).
  </li>
  <li>
    <b>Meta-mapping</b>. A meta-map will be generated if mapping is 
	enabled and <tt>-Mw</tt> and/or <tt>-Mh</tt> is greater than 1.
	If mapping is disabled, the meta-map settings indicate object tile 
	groups.
  </li>
  <li>
    <b>Data formats</b>. The default output is asm arrays with a 
    header file (<tt>-fts -fh</tt>). Graphics are word-arrays, Palette 
	and map data are halfword arrays.
  </li>
  <li>
    <b>Append/replace</b>. Currently, the default is to overwrite the 
    existing file, but it may make more sense to use append/replace 
	instead (<tt>-fa</tt>).
  </li>
  <li>
    <b>Filenames</b>. If no output name is given, it will be based 
	on the input name (which should always exist). The extension 
	<i>will</i> be one of the following: <tt>.c</tt> / <tt>.s</tt> / 
	<tt>.bin</tt> / <tt>.gbfs</tt>. Anything else will be changed.
  </li>
  <li>
    <b>Symbol names</b>. If no symbol name is given (<tt>-s</tt>), 
	it is based on the output name in overwrite mode, or the 
	input name in append mode (<tt>-fa</tt>). Invalid characters for 
	identifiers are replaced with underscores.
  </li>
  <li>
    <b>Directories</b>. Unless an absolute path is given, the base
	directory will be the current working directory. This means 
	<i>no</i> Drag&amp;Drop over a grit shortcut, because the cwd 
	there won't be what you'd want. Use the <tt>gritbat.bat</tt> file 
	for that if you must.
  </li>
  <li>
    <b>External tilefile</b>. <tt>-fx</tt> requires mapping, but 
	does <i>not</i> automatically set a <tt>-m</tt> option. 
  </li>
</ul>

<h3 id="ssec-dwim-over">1.3.2.
  Overrides</h3>
<ul>
  <li>
    <b>Transparent color vs palette</b>. This is ... complicated. 
	Use of <tt>-pT</tt> and <tt>-gT</tt> together is not advised.
  </li>
  <li>
    <b>Graphic types</b>. <tt>-gB16</tt> automatically means 
	bitmap graphics and no mapping (<tt>-gb -m!</tt>).
  </li>
  <li>
    <b>Filetypes</b>. The <tt>-ft</tt> options override the 
	filetype given by <tt>-o</tt>.
  </li>
  <li>
    <b>Global datatype/compression</b>. <tt>-U</tt> and <tt>-Z</tt> 
	set the datatype and compression options for all arrays, but they 
	can be overridden with data-specifoc options like <tt>-pu</tt> 
	and <tt>-gz</tt>.
  </li>
</ul>


<!-- ============================================================== -->

<h2 id="sec-eg">1.4.
  Examples</h2>
<p>
[[TODO]]
</p>


<!-- ============================================================== -->

<h2 id="sec-info">1.5.
  Additional information</h2>

<h3 id="ssec-info-grf">1.5.1.
  GRF files</h3>
<p>
I made myself a 
<a href="http://en.wikipedia.org/wiki/RIFF_(File_format)">RIFF</a> 
binary format because a) different loose binaries are somewhat annoying 
and b) they lose all context. A RIFF chunk looks like this:
</p>

<pre class=proglist>
<span class=keyw>struct</span> chunk_t {
    <span class=keyw>char</span> id[<span class=num>4</span>];
    u32  size;
    u8   data[<span class=num>1</span>];
};
</pre>

<p>
A 4-byte identifier, a 4-byte size field, indicating the size of the 
data (<i>not</i> the size of the whole chunk!) and a variable-length 
data array. A GRF chunk (pronounced &ldquo;griff&rdquo;) 
will look like this:
</p>

<pre class=proglist>
"RIFF" # {
    "GRF " # {
        "HDR " # { header info }
        "GFX " # { gfx data }
        "MAP " # { map data }
        "MTIL" # { metatile data }
        "MMAP" # { metamap data }
        "PAL " # { palette data }
    }
}
</pre>

<p>
The names are the (sub-)chunk identifiers, '#'s the size field, and the 
accolades indicate the data arrays. Each of the chunks inside "GRF " 
is actually optional, with the exception of the header. What goes into 
the header is still tentative, but for now it looks like this:
</p>

<pre class=proglist>
<span class=keyw>struct</span> GrfHeader
{
    u8  gfxAttr, mapAttr, mmapAttr, palAttr;
    u8  tileWidth, tileHeight;
    u8  metaWidth, metaHeight;
    u32 gfxWidth, gfxHeight;
};
</pre>

<p>
The attributes here are just the bitdepths for now, or 0 if the 
the item isn't exported, but this behaviour may change later. The 
tileWidth and tileHeight are the tile dimensions in pixels, and 
metaWidth/Height are the metatile dimensions in <b>tile</b>-units.
</p>

<div class=note>
<div class=nhcare>GrfHeader is unfinished</div>
<p>
I'm still considering what should go into the header here; things like 
map/metamap sizes may be useful, as would offsets, formats and other 
niceties. These may be added at a later date.
</p>
</div>

<p>
The following is a simple reader for GRF-formatted data.
</p>

<pre class=proglist>
<span class=keyw>#define</span> CHUNK_ID(a,b,c,d)   <!--
-->((u32)( (a) | (b)&lt;&lt;<span class=num>8</span> | (c)&lt;&lt;<span 
class=num>16</span> | (d)&lt;&lt;<span class=num>24</span> ))
<span class=keyw>#define</span> ID_RIFF             CHUNK_ID(<span 
class=str>'R'</span>,<span class=str>'I'</span>,<span 
class=str>'F'</span>,<span class=str>'F'</span>)
<span class=keyw>#define</span> ID_GRF              CHUNK_ID(<span 
class=str>'G'</span>,<span class=str>'R'</span>,<span 
class=str>'F'</span>,<span class=str>' '</span>)

<span class=cmt>//! Decompress a GRF item.</span>
<span class=keyw>bool</span> grf_decomp(<span class=keyw>const</span> <span 
class=keyw>void</span> *src, <span class=keyw>void</span> *dst)
{
    <span class=keyw>if</span>(src==NULL || dst==NULL)
        <span class=keyw>return false</span>;

    u32 header= *(u32*)src;
    uint size= header&gt;&gt;<span class=num>8</span>;
    
    <span class=keyw>switch</span>(header &amp; <span class=num>0xF0</span>)
    {
    <span class=keyw>case</span> <span class=num>0x00</span>:      <span 
class=cmt>// No compression</span>
        tonccpy(dst, (u8*)src+<span class=num>4</span>, size);     <span 
class=keyw>return true</span>;
    <span class=keyw>case</span> <span class=num>0x10</span>:      <span 
class=cmt>// LZ77</span>
        LZ77UnCompVram(src, dst);           <span class=keyw>return true</span>;
    <span class=keyw>case</span> <span class=num>0x20</span>:      <span 
class=cmt>// Huffman</span>
        HuffUnComp(src, dst);               <span class=keyw>return true</span>;
    <span class=keyw>case</span> <span class=num>0x30</span>:      <span 
class=cmt>// RLE</span>
        RLUnCompVram(src, dst);             <span class=keyw>return true</span>;
    <span class=keyw>default</span>:
        <span class=keyw>return</span> <span class=keyw>false</span>;
    }
}

<span class=cmt>//! Load grf data</span>
<span class=keyw>bool</span> grf_load(<span class=keyw>const</span> <span 
class=keyw>void</span> *src, <span class=keyw>void</span> *gfxDst, <span 
class=keyw>void</span> *mapDst, <span class=keyw>void</span> *palDst)
{
    u32 *src32= (u32*)src, id;
    
    <span class=cmt>// Must start with &quot;RIFF&quot; - &quot;GRF &quot;</span>
    <span class=keyw>if</span>(src==NULL || src32[<span 
class=num>0</span>] != ID_RIFF || src32[<span class=num>2</span>] != ID_GRF)
        <span class=keyw>return false</span>;
    
    uint sizeMax= src32[<span class=num>1</span>]-<span class=num>4</span>;   <span 
class=cmt>// GRF size</span>
    src32 += <span class=num>3</span>;                 <span 
class=cmt>// Skip GRF ID and size</span>

    uint ii, size;
    <span class=keyw>for</span>(ii=<span 
class=num>0</span>; ii&lt;sizeMax; ii += size+<span class=num>8</span>)
    {
        id= src32[<span class=num>0</span>];
        size= src32[<span class=num>1</span>];
        <span class=keyw>switch</span>(id)
        {
        <span class=keyw>case</span> CHUNK_ID(<span 
class=str>'G'</span>,<span class=str>'F'</span>,<span 
class=str>'X'</span>,<span class=str>' '</span>):
            grf_decomp(&amp;src32[<span 
class=num>2</span>], gfxDst);  <span class=keyw>break</span>;

        <span class=keyw>case</span> CHUNK_ID(<span 
class=str>'M'</span>, <span class=str>'A'</span>,<span 
class=str>'P'</span>,<span class=str>' '</span>):
            grf_decomp(&amp;src32[<span 
class=num>2</span>], mapDst);  <span class=keyw>break</span>;
            
        <span class=keyw>case</span> CHUNK_ID(<span 
class=str>'P'</span>,<span class=str>'A'</span>,<span 
class=str>'L'</span>,<span class=str>' '</span>):
            grf_decomp(&amp;src32[<span 
class=num>2</span>], palDst);  <span class=keyw>break</span>;
        }
        src32 += (size+<span class=num>8</span>)/<span class=num>4</span>;
    }

    <span class=keyw>return true</span>;
}
</pre>

<p>
Note that the header and metamap chunks are ignored here for 
simplicity's sake. Also note the decompression routine. I've made it 
a requirement that each item <b>must</b> have a header word compatible 
with the BIOS functions, even if there is no actual compression (hence 
the difference between <tt>-Z0</tt> vs <tt>-Z!</tt>). That way you can 
get the compression-type from the data itself, even if there's no 
actual compression. Another requirement is that each chunk must be 
word-aligned. This is actually part of the IFF-spec itself.
</p>
<p>
There is a reference to <code>tonccpy()</code> in <code>grf_decomp()</code>.
This is a <code>memcpy()</code> replacement that also works properly for 
GBA-VRAM. You can get it from 
<a href="http://www.coranac.com/2008/01/25/tonccpy/">coranac:tonccpy</a>, 
or you can just replace the call with <code>memcpy()</code> or any 
other copy routine if you're sure you won't run into trouble with those.
</p>

<p>
You can export to GRF using <tt>-ftr</tt>. You can also get GRF arrays 
by using <tt>-fr</tt>, but that presently only works for C and asm 
data. The extension used for the arrays there is &ldquo;Grf&rdquo;.
</p>

<div class=note>
<div class=nhcare>GRF bug!</div>
<p>
There was a small inconsistency between the GRF format and the way IFF 
chunks were supposed to be laid out. I had an additional size field 
after the chunk-title (like &ldquo;GRF &rdquo;) which should not have been 
there.
</p>
<p>
Thank you, Daniel Hyde for pointing this out.
</p>

</div>

<h3 id="ssec-info-shared">1.5.2.
  Shared data</h3>
<p>
In previous versions, you could have build up shared tileset with the 
<tt>-fx</tt> option. This would add new tiles to the tileset if they 
couldn't be found and save it to a bitmap. This worked, but because 
the runs were still essentially singular you ended up with intermediary 
palettes and tilesets unless you took steps to prevent it. And you had
to export the tileset separately afterwards.
</p>
<p>
As of v0.8 this is now different. If &hellip;
</p>

<ol>
  <li>you have multiple source files, and</li>
  <li><tt>-gS</tt>, <tt>-pS</tt> or <tt>fx</tt> is set</li>
</ol>

<p>
&hellip; grit will exclude the temporary palette and/or tileset (whatever is 
appropriate) from the individual parts and only export the completed 
sets at the end. The name of the shared data can be controlled with 
<tt>-S</tt> and that of the shared output file with <tt>-O</tt> 
(uppercase for shared, versus lowercase for individual). If you don't 
add these names, they will be taken from the lowercase versions; 
if those are absent too, the name of the first source file will be 
used as a basis.
</p>


<h3 id="ssec-info-todo">1.5.3.
  Todo list</h3>
<p>
Here are a few things that I'd like to add at some point. If anyone 
want to help flesh it out, that'd be great.
</p>

<ul>
  <li>
    The way the tile-file is handled now is kinda screwed up. Needs 
	to be straightened out.
  </li>
  <li>
    External meta-tileset. Right now it's just yer average 8x8 tiles.
  </li>
  <li>
    PCX support for external tileset. FreeImage doesn't allow PCX 
	writing.
  </li>
  <li>
    Better batch-run options. Possibly including the ability to 
	clump the data together somehow in a matrix.
  </li>
  <li>
    Grouped data. For example, if you have a bitmap with several sprite 
	animation frames, it's not useful to compress the whole thing 
	because you might want to uncompress them separately into VRAM.
	It'd be nice to have the compression apply per frame and use a 
	frame table. 
  </li>
  <li>
    Column-based instead of row-based map data. Could be useful for 
	horizontally scrolling maps.
  </li>
  <li>
    Long option names.
  </li>
</ul>


<h3 id="ssec-info-last">1.5.4.
  Last changes</h3>

<h4>v0.8.3 (20081207)</h4>
<ul>
  <li>
	Fixed ... well let's call it a clash of arguments regarding names for 
    shared data names if -S or -O wasn't supplied (thanks dovoto)
  </li>
  <li>
	grit files can now be used to add more input-files (thanks dovoto)
  </li>
  <li>
	map-entry offset -ma should work for the whole map-entry now, not just 
    the tile-index part.
  </li>
</ul>


<h4>v0.8.2 (20081129)</h4>
<ul>
  <li>
    The GRF format didn't quite follow IFF standards, it should work 
	with standard readers now.
  </li>
  <li>
    When creating a meta-map, the meta-tiles now have the affix 
	&ldquo;MetaTiles&rdquo; instead of &ldquo;Map&rdquo;. Yes, it does 
	mean things may break, but it simply makes more sense this way.
  </li>
  <li>
    The C-exported arrays now have <code>__attribute__(aligned(4))</code>, 
	so you don't have to worry about alignment in C anymore either.
  </li>
</ul>


<h4>v0.8 (20080212)</h4>
<ul>
  <li>
    Added <tt>-gS</tt> and <tt>-pS</tt> for shared tileset and 
	palettes and <tt>-O</tt> and <tt>-S</tt> for shared symbol/output 
	names. Also fixed the way shared runs were done: it excludes the 
	parts to be shared from the individual export, and do an additional 
	run with just the shared data afterwards.
  </li>
  <li>
    Added GRF format and the options that go with it (<tt>-ftr</tt>, 
	<tt>-fr</tt>)
  </li>
  <li>
    Added &lsquo;fake&rsquo; compression options (<tt>-Z0</tt>, etc) for 
	symmetry with the compression options. Like the other compression 
	options, the size will be in the upper 24 bits of the first word.
  </li>
  <li>
    Exit codes. Grit returns 1 on failure.
  </li>
  <li>
    Some internal refactoring. Hope I didn't screw up things too badly.
  </li>
</ul>

<h4>v0.7 (20070414)</h4>
<ul>
  <li>
    Added batch file <tt>grind.bat</tt> for drag/drop conversion. 
	(Yes, Dave, it's a batchfile, but sometimes you just want a
	quick sample without fussing.)
  </li>
  <li>
    Project rename. <tt>git</tt>'s now <tt>grit</tt>.
  </li>
  <li>
    Changed the way directories work. All relative paths start from 
    the current working directory, whatever that may be. This also
	fixes a bug when for dir-less <tt>-fx</tt> options (thanks dovoto).
  </li>
  <li>
    Default filetype is now assembly (<tt>-fts</tt>). If you're using 
	DKP or tonc template makefiles, this should not be a problem.
  </li>
  <li>
    Added <tt>-We</tt>, <tt>-Ww</tt>, <tt>-Ws</tt> aliases for 
	<tt>-W&lt;n&gt;</tt>.
  </li>
  <li>
    Added no converted output option <tt>-ft!</tt>.
  </li>
</ul>

<h4>v0.7b (20070317)</h4>
<ul>
  <li>
    Batchrun: Multiple bitmaps in one go (no wildcards though).
  </li>
  <li>
    Dwimming for transparency options (i.e., <tt>-gT</tt> and 
	<tt>-pT</tt> interaction)
  </li>
  <li>
    Error/warning/status logging functions (<tt>-W</tt>).
  </li>
  <li>
    External tilefile support (<tt>-fx</tt>).
</ul>
<p class=ni>
The batchrun and external tilefile support is still experimental.
YHBW.
</p>

<hr>

<br>

<div class=endtag>
Modified <span class=time>Nov 29, 2008</span>,
<a href="mailto:cearn@coranac.com">J Vijn</a>.
Get grit <a href="http://www.coranac.com/projects/#grit">here</a>
</div>

<hr>

<!-- [[footer]] -->
<table class=footer>
<tr>
  <td class=hdr_l><a href="index.htm">Prev</a>
  <td class=hdr_c><a href="index.htm">Contents</a>
  <td class=hdr_r><a href="gritmake.htm">Next</a>
<tr>
  <td class=hdr_l>Index
  <td class=hdr_c>
  <td class=hdr_r>Grit in projects
</table>
<!-- [[/footer]] -->

</body>
</html>


